Crate region

Cross-platform virtual memory API.

This crate provides a cross-platform Rust API for querying and manipulating virtual memory. It is a thin abstraction, with the underlying interaction implemented using platform specific APIs (e.g VirtualQuery, VirtualLock, mprotect, mlock). Albeit not all OS specific quirks are abstracted away; for instance, some OSs enforce memory pages to be readable, whilst other may prevent pages from becoming executable (i.e DEP).

This implementation operates with memory pages, which are aligned to the operating system’s page size. On some systems, but not all, the system calls for these operations require input to be aligned to a page boundary. To remedy this inconsistency, whenever applicable, input is aligned to its closest page boundary.

Note: a region is a collection of one or more pages laying consecutively in memory, with the same properties.

Parallelism

The properties of virtual memory pages can change at any time, unless all threads that are unaccounted for in a process are stopped. Therefore to obtain, e.g., a true picture of a process’ virtual memory, all other threads must be halted. Otherwise, a region descriptor only represents a snapshot in time.

Installation

This crate is on crates.io and can be used by adding region to your dependencies in your project’s Cargo.toml.

[dependencies]
region = "3.0.2"

Examples

• Cross-platform equivalents.

  let data = [0xDE, 0xAD, 0xBE, 0xEF];
  
  // Page size
  let pz = region::page::size();
  let pc = region::page::ceil(data.as_ptr());
  let pf = region::page::floor(data.as_ptr());
  
  // VirtualQuery | '/proc/self/maps'
  let q  = region::query(data.as_ptr())?;
  let qr = region::query_range(data.as_ptr(), data.len())?;
  
  // VirtualAlloc | mmap
  let alloc = region::alloc(100, Protection::READ_WRITE)?;
  
  // VirtualProtect | mprotect
  region::protect(data.as_ptr(), data.len(), Protection::READ_WRITE_EXECUTE)?;
  
  // ... you can also temporarily change one or more pages' protection
  let handle = region::protect_with_handle(data.as_ptr(), data.len(), Protection::READ_WRITE_EXECUTE)?;
  
  // VirtualLock | mlock
  let guard = region::lock(data.as_ptr(), data.len())?;

Modules

• page
  Page related functions.

Structs

• Allocation
  A handle to an owned region of memory.
• LockGuard
  A RAII implementation of a scoped lock.
• ProtectGuard
  A RAII implementation of a scoped protection guard.
• Protection
  A bitflag of zero or more protection attributes.
• QueryIter
  An iterator over the Regions that encompass an address range.
• Region
  A descriptor for a mapped memory region.

Enums

• Error
  A collection of possible errors.

Functions

• alloc
  Allocates one or more pages of memory, with a defined protection.
• alloc_at
  Allocates one or more pages of memory, at a specific address, with a defined protection.
• lock
  Locks one or more memory regions to RAM.
• protect^⚠
  Changes the memory protection of one or more pages.
• protect_with_handle^⚠
  Temporarily changes the memory protection of one or more pages.
• query
  Queries the OS with an address, returning the region it resides within.
• query_range
  Queries the OS for mapped regions that overlap with the specified range.
• unlock
  Unlocks one or more memory regions from RAM.

Type Aliases

• Result
  The result type used by this library.